.TH LIBPFM 3  "August, 2006" "" "Linux Programmer's Manual"
.SH NAME
pfm_get_event_name, pfm_get_full_event_name, pfm_get_event_mask_name, pfm_get_event_code,
pfm_get_event_mask_code, pfm_get_event_counters, pfm_get_num_events, pfm_get_max_event_name_len,
pfm_get_event_description, pfm_get_event_mask_description \- get event information
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.sp
.BI "int pfm_get_event_name(unsigned int " e ", char *"name ", size_t" maxlen ");"
.BI "int pfm_get_full_event_name(pfmlib_event_t *" ev ", char *"name ", size_t" maxlen ");"
.BI "int pfm_get_event_mask_name(unsigned int " e ", unsigned int "mask ", char *"name ", size_t" maxlen ");"
.BI "int pfm_get_event_code(unsigned int " e ", int *"code ");"
.BI "int pfm_get_event_mask_code(unsigned int " e ", unsigned int "mask ", int *"code ");"
.BI "int pfm_get_event_code_counter(unsigned int " e ", unsigned int " cnt ", int *"code ");"
.BI "int pfm_get_event_counters(int " e ", pfmlib_regmask_t "counters ");"
.BI "int pfm_get_num_events(unsigned int *" count ");"
.BI "int pfm_get_max_event_name_len(size_t *" len ");"
.BI "int pfm_get_event_description(unsigned int " ev ", char **" str ");"
.BI "int pfm_get_event_mask_description(unsigned int " ev ", unsigned int "mask ", char **" str ");"
.sp
.SH DESCRIPTION
The \fBpfm_get_event_name\fR function returns in \fBname\fR the event 
name given its opaque descriptor in \fBe\fR. The \fBmaxlen\fR argument 
indicates the maximum length of the buffer provided for \fBname\fR.
Up to \fBmaxlen-1\fR characters will be returned, not including the
termination character. Event names are returned in all upper case.
.sp
The \fBpfm_get_full_event_name\fR function returns in \fBname\fR the event 
name given the full event description in \fBev\fR. The description contains
the event code in \fBev->event\fR and optional unit masks descriptors in
\fBev->unit_masks\fR. The \fBmaxlen\fR argument indicates the maximum length
of the buffer provided for \fBname\fR.  If more than \fBmaxlen-1\fR characters
are needed to represent the event, an error is returned.
In case unit masks are provided, the final event name string is structured as:
event_name:unit_masks1[:unit_masks2]. Event names and unit masks names are
returned in all upper case.
.sp
The \fBpfm_get_event_code\fR function returns the event code in \fBcode\fR
given its opaque descriptor \fBe\fR.
.sp
On some PMU models, the code associated with an event is different based
on the counter it is programmed into. The \fBpfm_get_event_code_counter\fR
function is used to retrieve the event code in \fBcode\fR when the event \fBe\fR
is programmed into counter \fBcnt\fR. The counter index must correspond to the
index of a counting PMC register.
.sp
Given an opaque event descriptor \fBe\fR, the \fBpfm_get_event_counters\fR 
function returns \fBcounters\fR a bitmask of type \fBpfmlib_regmask_t where 
each bit set represents a PMU counter which can be used to program this 
event. The bitmask must be accessed accessor macros defined by the library.
.sp
It is possible to list all existing events for the detected host PMU
using accessor functions as the full table of events is not accessible
to the applications. The index of the first event is always zero,
then using \fBpfm_get_num_events\fR you get the total number of events.
Event descriptors are contiguous therefore a simple loop will allow
complete scanning. The typical scan loop is constructed as 
follows:
.sp
.nf
unsigned int i, count;
char name[256];
pfm_get_num_events(&count);
for(i=0;i < count; i++)
{
   pfm_get_event_name(i, name, 256);
   printf("%s\\n", name);
}
.fi

.so
The \fBpfm_get_num_events\fR function returns in \fBcount\fR the
total number of events supported by the host PMU.
.sp
The former \fBpfm_get_first_event\fR has been deprecated. You can simply
initialize your variable to 0 to point to the first event.
.sp
The former \fBpfm_get_next_event\fR has been deprecated. You need
to retrieve the total number of events for the host PMU
and then increment your loop variable until you reach that count.
.sp
The \fBpfm_get_max_event_name_len\fR function returns in \fBlen\fR 
the maximum length in bytes for the name of the events or its unit masks, if any,
available on one PMU implementation. The value excludes the string termination
character ('\\0').
.sp
The \fBpfm_get_event_description\fR function returns in \fBstr\fR the
description string associated with the event specified in \fBev\fR. 
The description is returned into a buffer that is allocated to hold the entire
description text. It is the responsibility of the caller to free the buffer when
it becomes useless by calling the \fBfree(3)\fR function.
.sp
The \fBpfm_get_event_mask_code\fR function must be used to retrieve the actual
unit mask value given a event descriptor in \fBe\fR and a unit mask descriptor
in \fBmask\fR. The value is returned in \fBcode\fR.
.sp
The \fBpfm_get_event_mask_name\fR function must be used to retrieve the name
associated with a unit mask specified in \fBmask\fR for event \fBe\fR. The
name is returned in the buffer specified in \fBname\fR. The maximum size
of the  buffer must be specified in \fBmaxlen\fR.
.sp
The \fBpfm_get_event_mask_description\fR function  returns in \fBstr\fR the
description string associated with the unit mask specified in \fBmask\fR for
the event specified in \fBev\fR. The description is returned into a buffer that
is allocated to hold the entire description text. It is the responsibility of
the caller to free the buffer when it becomes useless by calling the \fBfree(3)\fR
function.

.SH RETURN
All functions return whether or not the call was successful.  A return value of 
\fBPFMLIB_SUCCESS\fR indicates success, otherwise the value is the error code.
.SH ERRORS
.B PFMLIB_ERR_NOINIT
the library has not been initialized properly.
.TP
.B PFMLIB_ERR_FULL
the string buffer provided is too small
.TP
.B PFMLIB_ERR_INVAL
the event or unit mask descriptor, or the \fBcnt\fR argument is invalid, or a pointer argument is NULL.
.SH SEE ALSO
pfm_get_impl_counters(3), free(3)
.SH AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
.PP
